.\" Michael P. Reilly (C) 2014-2015  All rights reserved
.\" srvfilter.man $RelNo$  $Revision$
.\" Process this file with
.\" groff -man -Tascii svrfilter.1
.\"
.TH svrfilter 1 "February 2015" GNU/Python "User Manuals"
.SH NAME
svrfilter \- host management
.SH SYNOPSYS
.B svrfilter
.BI [ options ]
.SH DESCRIPTION
.B svrfilter
loads a data file and emits
.I user@host
strings based on criteria on the command-line.
Especially useful when used with
.BR sshcmd (1).
.SH OPTIONS
.TP
.B --help, -h
show usage/options and exit
.TP
.B --version
show version information and exit
.TP
.BI "\-\-file=" datafilename ", \-f " datafilename
data file with formatted entries
.TP
.B --quiet, -q
very list output
.TP
.B --verbose, -v
normal output
.TP
.BI "\-\-config=" conffilename
file with configuration options, the default is ~/.svrfilter.ini
.TP
.B \-\-check, \-C
validate the data file, return 1 if invalid
.TP
.B \-\-raw, \-R
dump raw data file of entries selected
.TP
.BI \-\-filter= regexp ", \-F " regexp
limit by matching patterns, prepend regexp with "^" to negate, may be repeated
.TP
.BI \-\-sort= field[,field] ", \-S " field[,field]
sort entries; fields may be prefixed with "-" to reverse the order;
default sort is "host"; see "Field names" section.
.TP
.BI \-\-comment= field[,field] ", \-c " field[,field]
add comment; default comment is an empty string; see "Field names" section.
.TP
.BI \-\-unique= field[,field] ", \-U " field[,field]
filter duplicate values; use case could be select only first hostname when
multiple found.
.TP
.BI \-\-product= product ", \-\-prod=" product ", \-p " product
limit by product, may be repeated, map contain comma-separated values,
may contain glob pattern
.TP
.BI \-\-env= environment ", \-e " environment
limit by environment, may be repeated, may contain comma-separated values,
may contain glob pattern
.TP
.BI \-\-host= hostname ", \-H " hostname
limit by hostname, may be repeated, may contain comma-separated values,
may contain glob pattern
.TP
.BI \-\-user= username ", \-U " username
limit by username, may be repeated, may contain comma-separated values,
may contain glob pattern
.TP
.BI \-\-net= network ", \-N " network
limit by network, may be repeated, may contain comma-separated values,
may contain glob pattern
.TP
.BI \-\-bridge= bridge ", \-B " bridge
limit by bridge, may be repeated, may contain comma-separated values,
may contain glob pattern
.TP
.B \-\-active
limit by active entries
.TP
.B \-\-inactive
limit by inactive entries
.TP
.B \-\-apptools
limit by entries with apptools
.TP
.B \-\-noapptools
limit by entries without apptools
.TP
.B \-\-primary
limit by primary bridges, based on the ordinal field
.TP
.B \-\-secondary
limit by secondary bridges, based on the ordinal field
.SH DESCRIPTION
.SS Field names
In the options, field names can be passed to the \-\-sort and \-\-comment
options.
The possible field values mostly correspond to the fields in the data file.
.IP active
The "active" field in the data file.
.IP apptools
The "apptools" field in the data file.
.IP bridge
The "bridge" field in the data file.
.IP domain
The "domain" value as determined from the "domainmap" values in the config
file.
.IP env
The "env" field in the data file.
.IP fqdn
If the "host" field is an IP address, then this is the same;
otherwise the value is the hostname with the domain added.
.IP host
The "host" field in the data file. Also "hostname".
.IP net
The "net" field in the data file.
.IP ordinal
The "ordinal" field in the data file.
.IP product
The "prod" field in the data file.  Also "prod".
.IP user
The "user" field in the data file.  Also "username".
.SH FILE FORMAT
See
.IR svrfilter (5)
for the format of the data file.
.SS Config format
The 'ini' format is supported at this time.  There are three sections
.IP default
The list of possible environment values can be replaced with a comma
separated list of values assigned to 'env'.
.IP programname
The section is actually the program name, not 'programname', this allows
the program to handle multiple names of the program which loads different
data files by default.
The only supported value at this time is 'datafile' which changes the
location of the datafilename.
.IP domainmap
Entries are mappings of the domain name for each 'env' value.  For example, having a '.qa.' subdomain for the 'test' environment.
.P
An example file might be:
.RS
.nf
[default]
env = qa, prod
[svrfilter]
datafile=~/.svrfilter.lst
[domainmap]
prod=.mycorp.com
stag=.mycorp.com
load=.qa.mycorp.com
test=.qa.mycorp.com
dev=dev.mycorp.com
.fi
.RE
Notice that the leading dot is not required but it is clearer when present.
.SH EXIT STATUS
.IP 0
Normal operation.
.IP 1
Error; see output.
.SH FILES
.IP $HOME/.svrfilter.ini
Configuration file for
.BR svrfilter .
Standard ini formatted file with configuration options,
see Config Format above.
.IP $HOME/etc/server.lst
Data filename, see
.IR svrfilter (5).
.SH ENVIRONMENT
.IP DEBUG
Enable debugging mode.  Same as '--DEBUG' option.
.IP HOME
Default directory of configuration files.
.SH DIAGNOSTICS
Set the DEBUG environment variable to a non empty string value, for example,
.BR "'DEBUG=1'" .
.SH BUGS
.P
Does not currently work under Python 3.x.
.SH EXAMPLE
.P
Display all active hosts in the test environment.
.nf
$ svrfilter --active --env=test
.fi
.P
Display all entries that match 'br2[0-9][0-9]'
.nf
$ svrfilter -F 'br2[0-9][0-9]'
.fi
.P
Display all inactive entries in the prod environment on the 'nyc' network
that have
apptools.
.nf
$ svrfilter --inactive --env=prod --net=nyc --apptools
.fi
.P
Similarly, display all active entries that do not have apptools.
.nf
$ svrfilter --active --noapptools
.fi
.SH AUTHOR
Michael P. Reilly <arcege@gmail.com>
.SH "SEE ALSO"
.BR sshcmd (1),
.BR svrfilter (5)
